TPWC AI Suppress (TPWCAS)
By TPW and -Coulum-
v1.01 20120625

Introduction:
-------------
One of the things sorely missing from Arma2 is reaction to passing bullets. An AI unit will often stand quite happily whilst bullets whiz by. This makes effective suppression of AI enemies difficult - you basically always have to aim to kill them since you can't make them keep their heads down by shooting nearby.

This addon aims to address this problem by making AI units react to passing projectiles. If a bullet snaps by within 10m of an AI unit, it will crouch/kneel (depending on movement), and if more than 5 bullets pass by a unit in 5 seconds, the unit will drop/crawl. After 10 seconds without bullets, the unit will return to its previous stance. 

Additionally, suppressive fire can alter the aiming shake, accuracy and courage of the suppressed unit. The more fire directed near a unit, the lower its skills will become. After 5 or so seconds without bullets, the skills will gradually return to normal.

Currently there is no "suppressed" eventhandler in the game engine, so TPWCAS aims to mimic one by using CBA to set up a per frame eventhandler, which checks whether there is currently an active bullet/shell projectile object, and if so then checks whether each unit has any bullets within a 10m radius. This allows TPWCAS to work for any opfor, blufor, independent or civilian on the map, whether editor-placed or spawned, without a crippling CPU overhead.

TPWCAS significantly changes gameplay, allowing for longer engagements and more thought required to survive them.


Installation:
-------------
TPWCAS comes as a script version and an addon version.
CBA (community base addons) is required for both versions.

Script version: 
Save tpwc_ai_suppress.sqf into your mission directory (or wherever you'd like really)
Call it with: null = [] execvm "tpwc_ai_suppress.sqf", in your init.sqf or in the init of any object on the map.

Addon version:
Unpack the addon version and call it by your favourite method. For more info on running mods please check out http://www.armaholic.com/plug.php?e=faq&q=18
Copy the configuration file to: your_arma_directory\userconfig\tpwc_ai_sup\tpwc_ai_sup.hpp (addon won't run without it)


Modes of Operation:
-------------------
You may elect to run TPWCAS in one of three modes depending on how much you'd prefer suppression to modify unit behaviour. The default is mode 3, allowing stance and skill modification under fire.

Mode 1: Basic (stance modifier)
* Units react to bullets passing within 10m
* Affects all units, in vehicles or not
* Units react identically to any kind of bullet fired from more than 25m away
* Units react to identically bullets from any side
* 1-5 bullets -->kneel/crouch
* >5 bullets --> drop/crawl
* Units regain previous stance after 10 seconds without nearby bullets

Mode 2: Light (stance modifier)
* Units react to bullets passing within 10m
* Only units not in vehicles are affected
* Bullets fired from less than 25m away are ignored
* Bullets from small calibre pistols and SMG are ignored
* Units react differently according to the side of the shooter
* 1-5 bullets --> kneel/crouch
* >5 bullets --> drop/crawl only if enemy shooter fired bullets
* Units regain previous stance after 10 seconds without nearby bullets

Mode 3: Full (stance and skill modifier)
* Units react to bullets passing within 10m
* Only units not in vehicles are affected
* Bullets fired from less than 25m away are ignored
* Bullets from small calibre pistols and SMG are ignored
* Units react differently according to the side of the shooter
* Friendly shooter: >0 bullets --> kneel/crouch
* Enemy shooter: 1-5 bullets --> kneel/crouch, >5 bullets -->drop/crawl 
* Friendly shooter: no skill reduction
* Enemy shooter: skills reduced according to number of bullets, unit placed into "combat" behaviour
* Units regain previous stance after 10 seconds without nearby bullets
* Units gradually regain skills after 5 or so seconds without bullets


Configuration:
--------------
TPWCAS is highly configurable. The script version has a number of well commented variables to change aspects of the system. The addon version allows the same variables to be changed in the tpwc_ai_sup.hpp config file. 


Caveats:
--------
* CBA is required. 
* TPWCAS only works on units not in vehicles.
* TPWCAS has not been tested in an MP environment as its primary goal is to enhance AI realism in SP. At this stage, any changes to unit stance will probably be local. Neither author is MP oriented or familiar with the vagaries of servers. You are welcome to contribute! 
* The system uses setunitpos to change unit stance. This means it will over-ride stance changes by those systems such as ASR-AI which use setunitposweak. However the stance changes are subordinate to those issued by a player to a squad. A squad given "stand" orders will not duck when bullets start flying. Nor will a fleeing unit.
* Because there is no way to actually tell who fired a particular bullet by querying the bullet (we tried!), TPWCAS relies on a fired eventhandler to set a global variable with the name of the shooter. This variable can then used to determine shooter side and distance, which allows the system (to have units either ignore bullets fired from the same side, and ignore bullets from any side if they are fired within 20m of the unit. In either case, units are not suppressed by their own bullets or nearby squadmates. TPWCAS is not bulletproof (pun intended), and may not operate perfectly under conditions of very heavy fire by multiple units or, if the framerate is too low.
* Mode 2 or 3 TPWCAS ignores rounds fired from pistols and low calibre SMGs. You won't be able to suppress the enemy by waving your pistol around. 
* Mode 3 TPWCAS implements changes to accuracy, courage etc under fire. The system plays nicely with ASR_AI, COSLX and other AI behaviour mods, but if you are concerned about clashes, then you can always run mode 1 or 2. 
* As far as the authors can tell, TPWCAS causes minimal drops to framerate even on low spec machines, with 50 or so AI taking pot shots at each other. Your mileage may vary depending on computer specs and number of AI. We take no responsibility if your computer explodes. 
* TPWCAS is in its infancy and probably won't work the way everyone wants it to. We welcome any feedback and suggestions.


Thanks:
-------
* Variable, Jedra and 2nd Ranger for initial ideas and suggestions.
* Orcinus for valuable input and suggestions.
* Froggluv for performance testing.
* Robalo for helpling to make his incredible ASR_AI skills addon and TPWCAS work nicely together 
* Falcon_565 for demonstrating the power of cba_fnc_addPerFrameHandler.
* BIS for an amazing piece of software which even allows scope for mods like this.


Changelog:
----------
* 1.00 20120623 - initital release

* 1.01 20120625 - Mode 3: Plays better with ASR AI skills. Units set to "combat" behaviour when suppressed. All modes: per frame speed optimisations.    